.TH grossd 8 "2008-05-04" "" ""
.if n .ad l
.nh
.SH "NAME"
\fBgrossd.conf\fP \- Greylisting of Suspicious Sources daemon configuration file
.SH "SYNOPSIS"
\fI@sysconfdir@/etc/grossd.conf\fP
.SH "DESCRIPTION"
\fIgrossd\fP\|(8) reads configuration data from \fI@sysconfdir@/etc/grossd.conf\fP
(or the file specified with \fB\-f\fP on the command line). 
An example configuration file is installed by default.  You have to
set some configuration options in order to get \fIgrossd\fP\|(8) running in 
your environment.  The format is as follows:
.sp
   name = value [ ; param ] ...
.PP
Not all options accept parameters \- 
refer to individual descriptions. The comment separator is 
`#', everything after it is ignored by the config file parser.
.SS "Network configuration options"
.IP "\fBhost\fP" 4
is the address the server should listen for queries.  Default is
`localhost'.
.IP "\fBport\fP" 4
is the port the server should listen for queries.  Default is
5525.
.IP "\fBsync_listen\fP" 4
is the address to listen for communication with the peer.  It
defaults to the \fBhost\fP setting.
.IP "\fBsync_peer\fP" 4
is the address of the peer used when running in clustered mode.
.IP "\fBsync_port\fP" 4
is the tcp port number to listen to and connect to in communication
with the peer.  Default is 5524.
.IP "\fBstatus_host\fP" 4
is the address \fIgrossd\fP\|(8) listens for status queries.  Default is `localhost'.
.IP "\fBstatus_port\fP" 4
is the port number \fIgrossd\fP\|(8) listens for status queries.  Default is
5522.
.IP "\fBprotocol\fP" 4
activates the server protocols \fIgrossd\fP\|(8) will support.  Valid settings are 
`sjsms', `postfix' and `milter'.
.IP "\fBmilter_listen\fP" 4
is the socket address for the Milter service.  The format is
`proto:port@host'.  Refer to Milter documentation for the specifics.
.SS "Core server options"
You can probably leave the default values for these settings.  If your daily
mail flow exceeds millions of messages per day you may want to tweak 
\fBquery_timelimit\fP and/or \fBpool_maxthreads\fP.  If you run \fIgrossd\fP\|(8) in a
server with limited memory you may want to adjust \fBfilter_bits\fP.
.IP "\fBfilter_bits\fP" 4
is the size of the Bloom filter.  The size will be 2^\fBfilter_bits\fP.
Lowering this value will increase the probability of false matches in each individual
filter.  Default is 24.
.IP "\fBnumber_buffers\fP" 4
is the number of Bloom filters used in the ring queue.  Raising this value will cause
an entry to stay in the server's memory longer.  Default is 8.
.IP "\fBrotate_interval\fP" 4
is the number of seconds between Bloom filter rotations.  Let
\fBN := number_buffers\fP and \fBI := rotate_interval\fP.
An entry will stay in the server's memory for \fBN \- 0.5 * I\fP
seconds on average.  Defaults to 3600 seconds (one hour).
.IP "\fBupdate\fP" 4
is the way server updates the database. Valid options are 
`grey' and `always'.  If set to `grey', which is the default,
\fIgrossd\fP\|(8) will update the database only if the response is
`\s-1STATUS_GREY\s+1'.  Setting it to `always' may reduce the impact on
\s-1DNS\s+1 servers.
.IP "\fBgrey_mask\fP" 4
is the mask for \fIgrossd\fP\|(8) to use when matching the 
`smtp\-client\-ip' against the database.  Default is 24, which makes \fIgrossd\fP\|(8)
to treat addresses like \fIa.b.c.d\fP as \fIa.b.c.0\fP.
Setting \fBgrey_mask\fP to 32 makes \fIgrossd\fP\|(8) to require that consecutive
attempts are made from the same `smtp\-client\-ip'.
.IP "\fBstatefile\fP" 4
is the full path of the file that the server uses to store
the state information.  Default is not to have a statefile.  You may
want to configure a \fBstatefile\fP especially if you do not configure
replication.
.IP "\fBpidfile\fP" 4
is the full path of the file \fIgrossd\fP\|(8) writes its pid into.
You can set parameter `check', if you want to keep \fIgrossd\fP\|(8) from
starting should pidfile already exist.
.Sh "Query constraints"
.IP "\fBgrey_delay\fP" 4
is the time in seconds new triplets are kept on the greylist.  Default is 180.
.IP "\fBquery_timelimit\fP" 4
is the query timeout in milliseconds.  You may have to adjust this if you
exceed millions of queries a day.
.IP "\fBpool_maxthreads\fP" 4
is the maximum threadcount per pool.  You may have to raise the limit from
the default if you get more than 100 queries per second and/or have slow
\s-1DNS\s+1 servers.  The rule of thumb is to decide how many queries you want
\fIgrossd\fP\|(8) to be able to handle per second, and multiply that with
\fBquery_timelimit\fP (in seconds, of course).  It defaults to 100.
.SS "Configuring server responses"
.IP "\fBblock_threshold\fP" 4
is the threshold after which \fIgrossd\fP\|(8) sends 
a permanent error to the client.  Every check that considers
`smtp\-client\-ip' as suspicious returns a value
(check weight).  When sum of these values gets equivalent or
greater than \fBblock_threshold\fP \fIgrossd\fP\|(8) sends a
\s-1STATUS_BLOCK\s+1 response.  Default is 0 which disables this
functionality.
.IP "\fBblock_reason\fP" 4
is the reason given when client is too suspicious, see
\fBblock_threshold\fP.  Default is \(lqBad reputation\(rq.
.IP "\fBgrey_threshold\fP" 4
is analogous to \fBblock_threshold\fP, except at the threshold \fIgrossd\fP\|(8)
sends a \s-1STATUS_GREY\s+1 response. Default is 1. If set to 0 \fIgrossd\fP\|(8) will greylist by default. This makes it possible to combine a traditional greylister and rbl checks.
.IP "\fBgrey_reason\fP" 4
is the reason given when client is suspicious enough to be greylisted, see
\fBgrey_threshold\fP.  Default is \(lqPlease try again later.\(rq.
.SS "Logging options"
.IP "\fBlog_method\fP" 4
is used to choose the logging method.  Currently the only implemented
method is `syslog', which is the default.
.IP "\fBlog_level\fP" 4
sets the logging verbosity.  Possible values in the order of increasing
verbosity are `error', `warning', `notice', `info' and `debug'.
\&\fBlog_level\fP defaults to `info'.
.IP "\fBsyslog_facility\fP" 4
is the facility syslog sends log messages with.  It defaults to
\&`mail'.
.IP "\fBstat_type\fP" 4
is the name of the requested statistic.  It is of multivalued type.  The
valid options are:
.PD 0
.RS 8
.TP 22
`full'
log all possible statistics,
.TP
`none'
no statistics logging,
.TP
`status'
basic set of statistics,
.TP
`since_startup'
basic set since the startup and
.TP
`delay'
log processing delay statistics.
.RE
.PD
.PP
.RS 4
Default is `none'.  Setting both `none' and `full'
is undefined.
.RE
.IP "\fBstat_interval\fP" 4
is the number of seconds between status log entries.  Default is 3600.
.SS "Configuring checks"
.IP "\fBcheck\fP" 4
is a multivalued option, that is, you can configure multiple checks by
setting \fBcheck\fP option multiple times.  Currently implemented checks
are `dnsbl', `dnswl', `rhsbl' and `blocker'.  
Refer to sections describing the checks below.  If you don't configure
any checks \fIgrossd\fP\|(8) will act as a traditional greylisting server.
.IP "\fBdnsbl\fP" 4
is a \s-1DNS\s0 domain name of the dnsbl that `dnsbl' \fBcheck\fP
will query.  There are no defaults, but the default configuration file
lists a few as an example.  If you have any locally administered
block lists then you should be aware that \fIgrossd\fP\|(8) makes all queries as
fully qualified.  You may assign different weights for the dnsbls,
default weight is 1.  Refer to \fBgrey_threshold\fP and \fBblock_threshold\fP
about the weights. \fBdnsbl\fP is a multivalued option.
.IP "\fBdnswl\fP" 4
is analogous to \fBdnsbl\fP.  Remember that \fBdnswl\fP is a
\fIdefinitive\fP check, that is \fIgrossd\fP\|(8) waits
for the check to complete
before deciding how to respond.  This may cause unwanted latency,
although you can adjust the maximum latency by \fBquery_timelimit\fP
option.  \fBdnswl\fP is highly recommended if you use \fIgrossd\fP\|(8) as a
traditional greylister.  This is a multivalued option.
.IP "\fBrhsbl\fP" 4
is analogous to \fBdnsbl\fP, but the check is made with the right
hand side of the sender address (the email domain) instead of the IP address.  
This is a multivalued option.
.IP "\fBblocker_host\fP" 4
is the host name of the Sophos blocker server.  This is used only if
\fBcheck\fP = `blocker' is set.
.IP "\fBblocker_port\fP" 4
is the \s-1TCP\s+1 port of the Sophos blocker service.  Default is 4466.
.IP "\fBblocker_weight\fP" 4
is the weight of the blocker check.  See description of
\fBgrey_threshold\fP and \fBblock_threshold\fP regarding the weights.
.SS "Sun Java System Messaging Server specific options"
You may configure the responses \fIgrossd\fP\|(8) sends over to grosscheck
library.
.IP "\fBsjsms_response_grey\fP" 4
is the mapping result template \fIgrossd\fP\|(8) uses for a \s-1STATUS_GREY\s+1
result.  Default is `$X4.4.3|$N%reason%', where `%reason%' is the template for
the reason string.
.IP "\fBsjsms_response_match\fP" 4
is the mapping result template \fIgrossd\fP\|(8) uses for a
\s-1STATUS_MATCH\s+1 result.  Default is `$Y'.
.IP "\fBsjsms_response_trust\fP" 4
is the mapping result template \fIgrossd\fP\|(8) uses for a
\s-1STATUS_TRUST\s+1 result.  Default is `$Y'.
.IP "\fBsjsms_response_block\fP" 4
is the mapping result template \fIgrossd\fP\|(8) uses for a
\s-1STATUS_BLOCK\s+1 result.  Default is
\&`$N%reason%', where `%reason%' is the template for the reason
string.
.SS "Postfix specific options"
.IP "\fBpostfix_response_grey\fP" 4
is the response template \fIgrossd\fP\|(8) uses for a \s-1STATUS_GREY\s+1
result.  Default is `action=defer_if_permit %reason%', where `%reason' is the
template for the reason string.
.IP "\fBpostfix_response_block\fP" 4
is the response template \fIgrossd\fP\|(8) uses for a \s-1STATUS_BLOCK\s+1
result.  Default is `action=reject %reason%', where `%reason' is the
template for the reason string.
.SH "MTA CONFIGURATION"
.SS "Sun Java System Messaging Server"
You have to add a mapping entry to set
\fB\s-1SJSMS\s+1\fP to query \fIgrossd\fP\|(8). It's also a good idea to exclude
postmaster and abuse addresses before querying \fIgrossd\fP\|(8).
.PP
Here is an example:
.PP
  ORIG_MAIL_ACCESS
  
  ! allow all DSNs and MDNs
    TCP|*|*|*|*|*|*|tcp_local||*|*  $Y$E
  ! allow all incoming mail to postmaster and abuse
    TCP|*|*|*|*|*|*|tcp_local|*|*|postmaster@*  $Y$E
    TCP|*|*|*|*|*|*|tcp_local|*|*|abuse@*  $Y$E
  ! use gross to check all triplets (client_ip,sender,recipient)
    TCP|*|*|*|*|SMTP/*|*|tcp_local|*|*|*  $[@libdir@/grosscheck.so,grosscheck,10.10.13.1,10.10.13.2,5525,$2,$=$8$_,$=$6$_,$=$4$_]
.PP
.PD 0
Mapping call parameters are as follows:
.RS 4
.IP "1. full path of the \fIgrosscheck.so\fP" 4
.IP "2. function name to call (always \fIgrosscheck\fP)" 4
.IP "3. first server's \s-1IP\s+1 address," 4
.IP "4. second server's \s-1IP\s+1 address," 4
.IP "5. \s-1UDP\s+1 port for server connections," 4
.IP "6. \s-1SMTP\s+1 client's \s-1IP\s+1 address," 4
.IP "7. envelope sender's email address," 4
.IP "8. envelope recipient's email address," 4
.IP "9. \s-1HELO/EHLO\s+1 string." 4
.PD
.SS "Postfix"
Grossd implements native Postfix policy delegation protocol. Just specify
grossd server address at the `smtpd_recipient_restrictions'
in the main configuration file
.PP
main.cf :
.PP
  /etc/postfix/main.cf:
      smtpd_recipient_restrictions =
          ... 
          reject_unauth_destination 
          check_policy_service inet:host:port
          ...
.PP
Refer to Postfix documentation at
<http://www.postfix.org> for specifics.
.SS "Exim"
Exim can be configured to query \fIgrossd\fP\|(8) via
Postfix policy delegation protocol.
.PP
Main section:
.PP
  GROSS_QUERY = sender=$sender_address\e\en\e\e
    recipient=$local_part@$domain\e\en\e\e
    client_address=$sender_host_address\e\en\e\e
    grossd_mode=single\e\en\e\en
.PP
Acl section:
.PP
  # gross
  warn
    set acl_c0 = ${readsocket{inet:127.0.0.1:5525}{GROSS_QUERY}}
  
  defer
    message = Please try again later.
    condition = ${if match {$acl_c0}{action=defer_if_permit}}
  
  deny
    message = ${if match {$acl_c0}{action=reject (.*)}{$1}\e\e
      {Rejected by Gross.}}
    condition = ${if match {$acl_c0}{action=reject}}
.SS "Sendmail"
Sendmail can query grossd via milter protocol. Insert this in
sendmail.mc and configure \fBmilter_listen\fP accordingly:
.PP
  INPUT_MAIL_FILTER(`Gross', `S=inet:5523@localhost, T=R:20s')
.PP
You can check if your version of Sendmail has Milter support compiled in
by issuing the following command:
.PP
  sendmail -bt -d0.1
.SH "SEE ALSO"
\fIgrossd\fP\|(8)
.PP
Gross project site:
<http://code.google.com/p/gross/>
.PP
Bloom filters: <http://en.wikipedia.org/wiki/Bloom_filter>
.SH "AUTHORS"
Eino Tuominen and Antti Siira
